package com.hongji.lms5xxcommunicator.grid.export;

import lombok.Value;

/**
 * <p>
 * 前端渲染用的“栅格代表点”：每个格子对应一个点，携带位置与统计信息。<br/>
 * 用于在 Three.js 等前端引擎中可视化展示。
 * </p>
 *
 * <p><b>字段说明</b></p>
 * <ul>
 *   <li>{@code row}/{@code col}：二维栅格索引。</li>
 *   <li>{@code index}：行优先线性索引（row * cols + col），便于前端 O(1) 定位。</li>
 *   <li>{@code x}/{@code y}：格中心的世界坐标。</li>
 *   <li>{@code z}：该格的代表高度（通常取 meanZ）。</li>
 *   <li>{@code count}：该格累计的点数。</li>
 *   <li>{@code hasData}：该格是否有有效数据。</li>
 * </ul>
 *
 * <p><b>用法</b></p>
 * <ol>
 *   <li>由 {@link ExportService} 在导出时构造。</li>
 *   <li>随 {@link GridDeltaPayload} 推送到前端。</li>
 *   <li>前端可用 {@code index} 快速更新点属性。</li>
 * </ol>
 *
 * @see ExportService
 * @see GridDeltaPayload
 */
@Value
public class GridPoint {
    /** 栅格行索引 */
    int row;
    /** 栅格列索引 */
    int col;
    /** 行优先线性索引：row * cols + col（便于前端 O(1) 定位） */
    int index;
    /** 世界坐标 X（格中心） */
    double x;
    /** 世界坐标 Y（格中心） */
    double y;
    /** 该格代表高度（通常用 meanZ） */
    double z;
    /** 该格累计点数 */
    int count;
    /** 该格是否有数据 */
    boolean hasData;
}
